Readme for pscp v0.49b-07 (3 Nov 2002)

What?
-----

pscp is an implementation of the secure copy (scp) protocol under RISC OS.
scp is a secure file transfer protocol, similar to rcp under Unix, which
encrypts all data sent (including your password) to protect it from people
listening over the network, and also provides safety from various kinds of
security attacks on the network.

pscp is a sister application to SSHProxy, which performs the terminal
session part of the SSH protocol, while pscp provides the file transfer part. 

Why is SSH useful?
------------------

Many people do not realise that when they use a standard protocol, such as
telnet, FTP, POP3 etc, their passwords and all their data is sent 'in the
clear'.  This means that anyone with a computer that is hooked up to the
network along which it travels can run a simple program on their computer and
see what you are typing - capture your passwords, read your email and so on.
The danger is most present close to the machines at each end of the
connection - for example, anyone one on the same run of ethernet cable as
either end of the connection can read all the data.  Other vulnerabilities
include 'IP spoofing', in which someone else can pretend to be the remote
machine, so when you login to send your email, you send your password and all
your data to some hacker, rather than the reputable mail server you thought
you were talking to.  SSH prevents these problems by encrypting the data so
no-one can eavesdrop, and by each end having a private key, which allows you
to be sure that you are talking to who you think you are talking to.

SSH 1 or SSH 2?
---------------

There are two versions of the SSH protocol out there.  SSH 2 is a brand new
protocol from SSH 1, and is completely incompatible with SSH 1, while
corrects some rare security issues in SSH 1. Also, the offical SSH 2 server
is only available under a restrictive licence, which makes it free for only a
limited set of organisations and individuals.  OpenSSH, a GPLd SSH 2 server
has recently been released, but due to the previous restrictions, uptake of
SSH 2 servers has been slow.  To add to this, some SSH 2 servers can be built
with an SSH 1 backwards compatibility mode, but not the other way around. 
Therefore pscp and SSHProxy implement SSH 1, to allow the widest possible
use.

Running pscp
------------

First you need to have installed an Internet stack (you're almost certain to
have one of those anyway).  Then merge the supplied !System with your
existing copy.  It is highly recommended that you use an automatic tool to do
this - either the Configure utility of a New Boot sequence, or !SysMerge, for
pre-New Boot (RISC OS 3.1) machines.

pscp is a command line utility - once !pscp has been seen by the Filer, the
commands pscp or scp are available.  Both do the same things - typing *pscp
will generate the following summary of options:

PuTTY Secure Copy client
RISC OS port 0.49b.01 Nov 12 2000 ported by theo@markettos.org.uk
Usage: pscp [options] [user@]host:source \"target\"
       pscp [options] \"source\" [\"source\"...] [user@]host:target
       pscp [options] -ls user@host:filespec
Options:
  -p        preserve file attributes
  -q        quiet, don't show statistics
  -r        copy directories recursively
  -v        show verbose messages
  -P port   connect to specified port
  -pw passw login with specified password
  -t        Append NFS style (,xxx) filetypes

Think of the basic syntax as similar to:

*Copy Source Destination

but Source or Destination (but not both) can be on another machine.  It's
probably best illustrated by example:

*pscp fred@somemachine.somewhere.com:/home/fred/file \"adfs::4.$.fred\"

will connect to the computer somemachine.somewhere.com, log in as fred
(prompting for fred's password if necessary), then downlond the file
/home/fred/file and store it on the local machine as adfs::4.$.fred

Note that due to a clash between the Unix scp notation for specifying a
remote machine and RISC OS filenames (in particular their use of @ and : ),
it's necessary to surround each RISC OS filename with \" - eg \"filename\"

Similarly, uploading files to a remote machine can be done with:

*pscp -r \"Boot:Choices.Boot\" joe@server:/etc/boot

which will take the local directory Boot:Choices.Boot, log in as joe to the
machine called server, and recursively upload it (see option -r below) and
its contents as /etc/boot.  Specifying more than one local file or directory
to upload should upload all of them.  Note that the SSH server will obey file
permissions on the remote machine, so if user joe doesn't have write access
to the directory /etc then they may not be allowed to store any files there.

To list files on the remote machine, use:

*pscp -ls testuser@somemachine:/home/testuser

will produce a file listing of the Unix 'ls -al' format:

total 27
drwx--x--x   4 testuser testuser     1024 Sep  1  1999 .
drwxr-xr-x  97 root     root         2048 Nov 10 14:46 ..
-rw-------   1 testuser testuser       66 Feb  6  1999 .bash_history
-rw-r--r--   1 testuser testuser       24 May  1  1997 .bash_logout
-rw-r--r--   1 testuser testuser      538 May  4  1997 .bash_profile
-rw-r--r--   1 testuser testuser      124 May  1  1997 .bashrc
-rw-r--r--   1 testuser testuser    10326 May  1  1997 .pinerc
drwxr-xr-x   2 root     root         1024 Sep  1  1999 public_html

Note that you must have the 'ls' command on the path of the remote machine,
and the rights to be able to execute commands on it (eg commercial webservers
may not have this).  Copying files is unaffected if 'ls' is absent.

Options
-------

-p              Preserve
Preserve time and date stamps between local and remote machines

-q              Quiet
Don't show the progress of the transfer

-r              Recurse
Recurse down directory trees, copying everything within them

-v              Verbose
Show more details of the operation as it progresses, and details of the
client/server dialogue

-P <port>       Port
Connect to port <port> on the server rather than the default of 22

-pw <password>  Password
Login with the supplied password (note the password will obviously be visible
in cleartext on your command line)

-t              Filetypes
Append NFS style filetypes to outgoing files, and interpret them on incoming
files.  This involves adding a three digit hexadecimal filetype number to the
end of the filename (eg TextFile,fff )


If you yet a warning such as:

  *** Don't recognise this remote host - adding to local list of known hosts
  *** Make sure they are who they claim to be...

this is due to SSH's use of 'host keys'.  When tyou connect to a remote
machine 'fred', these make it possible to check whether the machine called
'fred' you connected to last time is actually the same machine (keys agree)
or someone else pretending to be them (keys differ).  The keys are stored on
your machine in a choices file (see below for details) - this is the same
format as the Unix version of SSH, so if your network supplies a known-hosts
file, you can put it here (for example, a list of Cambridge University
machines can be found at http://www-uxsup.csx.cam.ac.uk/CD/ ).  If the
machine was known before and the keys match, pscp will confirm this, while if
the keys do not match, pscp will give you a warning.  If you are at all
suspicious, do not continue to login - however, if the system has poor system
administration the key change might be to loss of it at the server, such as a
disc crash or a system upgrade, in which case it is safe.  If you are in
doubt, check by some other means.  pscp will give you a warning as above if
you've not logged into this host before - you should be cautious, but not
unduly worried in this case.  It will store the host key for future use, so
you should only get this once per machine.

If you have RISC OS 3.1 and an old Boot sequence,
then you probably don't have a Choices: path, so these settings will be
stored within !pscp, otherwise they will be stored within !Boot.Choices as
pointed to by <Choices$Write> - this can be changed by setting pscp$Choices
to a path in !pscp.!RunPSCP.  On the path will be stored the CryptRandom seed
(also used by SSHProxy and any other applications using CryptRandom), and a
KnownHosts file (shared with SSHProxy) as detailed above.

Building pscp
-----------------

The source for pscp is available at http://www.markettos.org.uk/
To build it you will need:

  A C compiler, I've used Acorn C v5 and GCC 2.95.4 (GCC now used)
    Some versions of Acorn C seem to hang when compiling some source files
    (in particular sshblowf.c) - making the makefile use GCC for those
    files only is a useful workaround - hopefully this has been fixed in
    later versions of Norcroft.
  A make tool (eg amu)

  Libraries:
    UnixLib (internal GCC 2.95.4 version used), from
      http://www.hard-mofo.dsvr.net/unixlib/index.html or as included 
      in GCC 2.95.4 releases (GCC version is newer)

Later versions of libraries should be OK, although I haven't tested them.  If
you have any problems finding any of these or with compiling, let me know.

Contacting
----------

The latest version of pscp should be available from
http://www.markettos.org.uk/ including binaries and sources. 
SSHProxy and CryptRandom are also available from the same address.

The RISC OS version is written by Theo Markettos, who is contactable as
follows:

email: theo@markettos.org.uk

post:
5 Willow Close
Liphook
Hampshire
GU30 7HX
UK

pscp is based on PuTTY 0.49beta, a Windows SSH client by Simon Tatham. 
PuTTY is available at http://www.chiark.greenend.org.uk/~sgtatham/putty.html
The official SSH Data Communications Inc. servers are available at
http://www.ssh.fi

Legalities
----------

See the file Copyright for more details
